No part of this work may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying, recording, or by any information storage and retrieval system, without permission in writing from the publisher. However, you are permitted to make copies of this work, printed or otherwise, as long as said copies are for your personal use only.
Introduction
------------
This time, we'll look at list boxes, how to figure out what item has been selected, how to change an item, add and remove items, and how to change an entire list. This part of the tutorial assumes that you went through the last two parts, or at least have a working knowledge of MicroPhone scripting and ResEdit.
List Boxes
----------
List boxes are like any other item in a dialog, such as buttons and static text. However, when you go into ResEdit, you'll notice that there is no option for creating a list box. Instead, you use the useritem control, which looks like a gray box (make sure that the useritem is enabled by clicking on the appropriate checkbox in ResEdit). Take a look at the following script:
Remark "--- 1 ---"
Set Variable * d0 from Expression "'List'"
Set Variable * d from Expression "MPDialogerPro(d0)"
DialogerPro does not know that the useritem you put into your dialog is a list box, so if you bring up the dialog without doing anything else, you'll see a rectangle instead of a list. DialogerPro draws a rectangle as a default when it spots a useritem in the dialog. To test this, run the script called "1" in this settings document.
So, how do we tell DialogerPro that we want it to treat the useritem as a list box? Look at this script:
Remark "--- 2 ---"
Set Variable * d0 from Expression "'List'"
Set Variable * d4 from Expression "'4◊userList'"
Set Variable * d from Expression "MPDialogerPro(d0,d4)"
One of the parameters we pass to DialogerPro corresponds to item number 4 in the dialog (the useritem). We are giving DialogerPro the instruction to treat the useritem as a list box, hence the command userList. Run script "2" to see this in action. You should see an empty list, complete with scrollbar.
The following script will actually put some default items into the list:
Remark "--- 3 ---"
Set Variable * d0 from Expression "'List'"
Set Variable * d4 from Expression "'4◊userList^MApple^MBanana^MCherry'"
Set Variable * d from Expression "MPDialogerPro(d0,d4)"
Hit Handler
-----------
Let's add a bit more complexity to the dialog by creating a hit handler. Now, whenever the dialog receives a hit, the hit handler will get executed. See the following scripts:
Remark "--- 4 ---"
Set Variable * d0 from Expression "'List^Mon List Handler 4'"
Set Variable * d4 from Expression "'4◊userList^MApple^MBanana^MCherry'"
Set Variable * d from Expression "MPDialogerPro(d0,d4)"
Remark "--- List Handler 4 ---"
If Expression "itemHit = '1'"
Alert * OK "'You clicked the OK button'"
Else If Expression "itemHit = '2'"
Alert * OK "'You clicked the Cancel button'"
Else If Expression "itemHit = '3'"
Alert * OK "'You clicked the Other button'"
Else If Expression "itemHit = '4'"
Beep
End If
This hit handler really doesn't do us much good. It tells us what we've clicked on, but otherwise, it doesn't do much. Let's create another hit handler that will show us which item in the list we selected:
Remark "--- 5 ---"
Set Variable * d0 from Expression "'List^Mon List Handler 5'"
Set Variable * d4 from Expression "'4◊userList^MApple^MBanana^MCherry'"
Set Variable * d from Expression "MPDialogerPro(d0,d4)"
Remark "--- List Handler 5 ---"
If Expression "itemHit = '1'"
Alert * OK "'You clicked the OK button'"
Else If Expression "itemHit = '2'"
Alert * OK "'You clicked the Cancel button'"
Else If Expression "itemHit = '3'"
Alert * OK "'You clicked the Other button'"
Else If Expression "itemHit = '4'"
Do XCMD * MPChangerPro "dialog,'5◊' & MPContentsPro(dialog,'4','Long')"
End If
Now, whenever you choose something in the list, you'll see it appear above the list. Try it by running script "5". Here, we introduce the use of MPChangerPro, which is an XCMD that allows you to make changes to a dialog that is already displayed. Here, we tell it to change item number 5 to display the contents of the selection in item number 4. Also new here is MPContentsPro, which returns the contents of the specified item in the dialog. The syntax is:
where dialogPointer refers to the dialog whose contents we wish to inspect. Usually, just pass the variable "dialog" which will point to the current DialogerPro-generated dialog on the screen. ItemNumber refers to the number of the item in the dialog. The optional parameter can be 'Short', 'Long', or 'All'. To see what happens when you use the optional parameter of 'Short', try script "6".
Going Further
-------------
DialogerPro is very powerful, and its capabilities can be overwhelming. However, with a little patience, you too can master it. The best way to learn it is from example. Take a look at the scripts that drive all of the examples in Open Mike. Many use DialogerPro dialogs. By printing the scripts and studying them, you'll see what's possible and how to harness the power under MicroPhone's hood. Good luck with your adventures!
